Agent networks API link#824
Conversation
📝 WalkthroughWalkthroughThis PR adds a new "Agent Network" documentation section, including navigation entries in the API and docs sidebars, and a comprehensive set of new MDX pages covering overview, quickstart, architecture, providers, policies, limits, guardrails, and usage/logs. It also updates the OpenAPI generation script in package.json to use a Go-based generator instead of swagger-codegen. ChangesAgent Network Documentation
OpenAPI Generation Script
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
⚔️ Resolve merge conflicts
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
src/components/NavigationAPI.jsxOops! Something went wrong! :( ESLint: 9.39.4 TypeError: Converting circular structure to JSON src/components/NavigationDocs.jsxOops! Something went wrong! :( ESLint: 9.39.4 TypeError: Converting circular structure to JSON src/pages/agent-network/global-limits.mdxOops! Something went wrong! :( ESLint: 9.39.4 TypeError: Converting circular structure to JSON
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
package.json (1)
11-11: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winUnpinned upstream spec source (
mainbranch) makes doc generation non-reproducible.Fetching directly from
netbirdio/netbird'smainbranch means the generated API pages can change or break silently whenever the upstream repo's spec changes, with no way to reproduce a prior build. Consider pinning to a tagged release/commit SHA and bumping it deliberately.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@package.json` at line 11, The docs generation command is pulling the OpenAPI spec from netbirdio/netbird main, which makes builds non-reproducible. Update the gen script in package.json to fetch a pinned upstream reference instead of main, using a specific tag or commit SHA, and keep the rest of the generator flow unchanged. Adjust the command so future bumps are deliberate and easy to review.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@package.json`:
- Line 11: The package.json gen script currently downloads
generator/openapi/openapi.yml with curl without failing on HTTP errors, so
invalid responses can still flow into the downstream generator. Update the gen
command to make the curl invocation fail fast on non-2xx responses by adding the
appropriate fail flag, and keep the rest of the pipeline unchanged so go run .
and generator/index.ts only run after a successful download.
In `@src/pages/agent-network/policies/index.mdx`:
- Around line 14-18: The MDX page uses the Note component in the agent-network
policies content but does not import it, which will break the build unless it is
globally available. Add the Note import at the top of the MDX file, using the
custom MDX components entry from `@/components/mdx`, and ensure the Note usage in
the page resolves to that imported symbol.
- Around line 40-52: The curl example in the MDX page uses a real
production-looking hostname and disables TLS verification with -k, which should
not be shown in public docs. Update the example to use a placeholder endpoint
instead of sailcloth.netbird.ai, and remove -k so certificate checks remain
enabled unless the surrounding documentation explicitly justifies bypassing
them. Keep the change within the existing example block so it remains consistent
with the rest of the page.
---
Nitpick comments:
In `@package.json`:
- Line 11: The docs generation command is pulling the OpenAPI spec from
netbirdio/netbird main, which makes builds non-reproducible. Update the gen
script in package.json to fetch a pinned upstream reference instead of main,
using a specific tag or commit SHA, and keep the rest of the generator flow
unchanged. Adjust the command so future bumps are deliberate and easy to review.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 44882364-869f-4484-b944-5aad7bc6ad7f
⛔ Files ignored due to path filters (25)
public/docs-static/img/agent-network/global-limits/agent-network-create-global-limit.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/global-limits/agent-network-global-limits-list.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/how-it-works/agent-network-diagram-internal-resources.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/how-it-works/agent-network-diagram-llm-apis.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/overview/agent-network-control-center-v2.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/overview/agent-network-control-center.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/overview/agent-network-internal-resources-policy.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/overview/agent-network-llm-policy.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/policies/agent-network-access-log.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/policies/agent-network-create-policy.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/policies/agent-network-guardrails.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/policies/agent-network-policy-limits.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/providers/agent-network-create-provider.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/providers/agent-network-providers-list.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/quickstart/agent-network-add-policy.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/quickstart/agent-network-add-provider.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/quickstart/agent-network-agent-config.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/quickstart/agent-network-connect-device.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/quickstart/agent-network-empty-endpoint.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/quickstart/agent-network-endpoint.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/quickstart/agent-network-usage-and-logs.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/usage-and-logs/agent-network-access-log-filters.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/usage-and-logs/agent-network-access-logs.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/usage-and-logs/agent-network-log-collection.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/usage-and-logs/agent-network-usage-overview.pngis excluded by!**/*.png
📒 Files selected for processing (15)
package.jsonsrc/components/NavigationAPI.jsxsrc/components/NavigationDocs.jsxsrc/pages/agent-network/global-limits.mdxsrc/pages/agent-network/how-it-works.mdxsrc/pages/agent-network/index.mdxsrc/pages/agent-network/policies/guardrails.mdxsrc/pages/agent-network/policies/index.mdxsrc/pages/agent-network/policies/limits.mdxsrc/pages/agent-network/providers.mdxsrc/pages/agent-network/quickstart.mdxsrc/pages/agent-network/usage-and-logs/access-logs.mdxsrc/pages/agent-network/usage-and-logs/index.mdxsrc/pages/agent-network/usage-and-logs/log-collection.mdxsrc/pages/agent-network/usage-and-logs/usage-overview.mdx
| "gen:last-updated": "node scripts/generate-last-updated.mjs", | ||
| "gen:sitemap": "node scripts/generate-sitemap.mjs", | ||
| "gen": "swagger-codegen generate -i https://raw.githubusercontent.com/netbirdio/netbird/main/management/server/http/api/openapi.yml -l openapi -o generator/openapi && npx ts-node generator/index.ts gen --input generator/openapi/openapi.json --output src/pages/ipa/resources", | ||
| "gen": "mkdir -p generator/openapi && curl -L -o generator/openapi/openapi.yml https://raw.githubusercontent.com/netbirdio/netbird/main/shared/management/http/api/openapi.yml && (cd generator && go run .) && npx ts-node generator/index.ts gen --input generator/openapi/expanded.yml --output src/pages/ipa/resources", |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Add -f/--fail to the curl call.
Without -f, curl -L -o writes HTTP error bodies (e.g. a GitHub 404/5xx page) to openapi.yml and still exits 0, letting go run . and the downstream generator proceed on invalid input instead of failing fast with a clear network error.
🔧 Proposed fix
- "gen": "mkdir -p generator/openapi && curl -L -o generator/openapi/openapi.yml https://raw.githubusercontent.com/netbirdio/netbird/main/shared/management/http/api/openapi.yml && (cd generator && go run .) && npx ts-node generator/index.ts gen --input generator/openapi/expanded.yml --output src/pages/ipa/resources",
+ "gen": "mkdir -p generator/openapi && curl -fL -o generator/openapi/openapi.yml https://raw.githubusercontent.com/netbirdio/netbird/main/shared/management/http/api/openapi.yml && (cd generator && go run .) && npx ts-node generator/index.ts gen --input generator/openapi/expanded.yml --output src/pages/ipa/resources",📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "gen": "mkdir -p generator/openapi && curl -L -o generator/openapi/openapi.yml https://raw.githubusercontent.com/netbirdio/netbird/main/shared/management/http/api/openapi.yml && (cd generator && go run .) && npx ts-node generator/index.ts gen --input generator/openapi/expanded.yml --output src/pages/ipa/resources", | |
| "gen": "mkdir -p generator/openapi && curl -fL -o generator/openapi/openapi.yml https://raw.githubusercontent.com/netbirdio/netbird/main/shared/management/http/api/openapi.yml && (cd generator && go run .) && npx ts-node generator/index.ts gen --input generator/openapi/expanded.yml --output src/pages/ipa/resources", |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@package.json` at line 11, The package.json gen script currently downloads
generator/openapi/openapi.yml with curl without failing on HTTP errors, so
invalid responses can still flow into the downstream generator. Update the gen
command to make the curl invocation fail fast on non-2xx responses by adding the
appropriate fail flag, and keep the rest of the pipeline unchanged so go run .
and generator/index.ts only run after a successful download.
| <Note> | ||
| This page explains how to create and manage access to AI providers and gateways. If you are | ||
| looking for a guide on how to manage access to internal resources, see | ||
| [Access Control](/manage/access-control). | ||
| </Note> |
There was a problem hiding this comment.
🩺 Stability & Availability | 🔴 Critical | ⚡ Quick win
Import Note before using it.
This page renders <Note> but never imports it, so the MDX build will fail unless the component is globally injected. Add the import at the top of the file.
Fix
+ import { Note } from '`@/components/mdx`'As per path instructions, import custom components from @/components/mdx when you use them.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <Note> | |
| This page explains how to create and manage access to AI providers and gateways. If you are | |
| looking for a guide on how to manage access to internal resources, see | |
| [Access Control](/manage/access-control). | |
| </Note> | |
| import { Note } from '`@/components/mdx`' | |
| <Note> | |
| This page explains how to create and manage access to AI providers and gateways. If you are | |
| looking for a guide on how to manage access to internal resources, see | |
| [Access Control](/manage/access-control). | |
| </Note> |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/agent-network/policies/index.mdx` around lines 14 - 18, The MDX
page uses the Note component in the agent-network policies content but does not
import it, which will break the build unless it is globally available. Add the
Note import at the top of the MDX file, using the custom MDX components entry
from `@/components/mdx`, and ensure the Note usage in the page resolves to that
imported symbol.
Source: Path instructions
| ```bash | ||
| curl -vk https://sailcloth.netbird.ai/v1/chat/completions \ | ||
| --header "Content-Type: application/json" \ | ||
| --data '{ | ||
| "model": "gpt-5.5", | ||
| "messages": [ | ||
| { | ||
| "role": "user", | ||
| "content": "What is NetBird?" | ||
| } | ||
| ] | ||
| }' | jq | ||
| ``` |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Replace the concrete hostname and drop -k.
This example disables TLS verification and hard-codes a production-looking host into a public MDX page. Use a placeholder endpoint and keep certificate checks enabled unless the page explicitly explains why they must be bypassed.
Fix
- curl -vk https://sailcloth.netbird.ai/v1/chat/completions \
+ curl -v https://<agent-network-endpoint>/v1/chat/completions \As per coding guidelines, src/pages/**/*.{md,mdx}: Never include real customer names, internal hostnames, IPs, or production credentials in MDX documentation or public/ files — use placeholders instead.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```bash | |
| curl -vk https://sailcloth.netbird.ai/v1/chat/completions \ | |
| --header "Content-Type: application/json" \ | |
| --data '{ | |
| "model": "gpt-5.5", | |
| "messages": [ | |
| { | |
| "role": "user", | |
| "content": "What is NetBird?" | |
| } | |
| ] | |
| }' | jq | |
| ``` |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/agent-network/policies/index.mdx` around lines 40 - 52, The curl
example in the MDX page uses a real production-looking hostname and disables TLS
verification with -k, which should not be shown in public docs. Update the
example to use a placeholder endpoint instead of sailcloth.netbird.ai, and
remove -k so certificate checks remain enabled unless the surrounding
documentation explicitly justifies bypassing them. Keep the change within the
existing example block so it remains consistent with the rest of the page.
Source: Coding guidelines
2 participants
Summary by CodeRabbit
New Features
Documentation